Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 096 / condr202.arc / CONDOR.DOC next >

Wrap

Text File | 1987-05-01 | 36.0 KB | 1,072 lines

CONDOR.EXE - 15.1A Doorware Link for PCBoard Ver 2.01 (C) Copyright 1987 Intermountain Softworks Please study documentation for proper use May 1, 1987 Intermountain Softworks is pleased to add a short but useful software product to the worldwide PC-standard inventory. Although CONDOR.EXE will only interest PCBoard system operators running enhanced versions 11.8D/E under license, we are hopeful that BBS'ers everywhere will find more reasons to enjoy their local systems, and support them to the fullest. CONDOR will thoroughly convince 15.1A releases of RBBS-PC "doorware" they're running under RBBS. For suggested sources of these applications, refer to our resource list at the end of this document. Users are cordially invited to visit our own PCBoard system at 509/529-7229. Our maximum bit rate is 2400. We operate 24 hours on weekends, and between 1600h and 0600h weekdays, Pacific. Weekdays, the system is subject to availability after midnight. CONDOR.EXE - Installation and Use 1.0 - Acknowledgements 2 1.1 - Limited License 3 1.2 - Shareware Distribution 3 1.3 - What's New With Condor Two 4 1.4 - Version-Specific Requirements 5 1.5 - What's Needed 5 1.6 - Overview 6 1.7 - Multi-Node Environment 7 2.0 - Getting Started 7 2.1 - Batch Files 9 2.2 - Subdirectories 11 2.3 - Disk Buffers 12 2.4 - Error Messages 12 3.0 - Resources 13 3.1 - A Note for Door Developers 13 Appendix A - Error Messages 14 Appendix B - CONDOR Problem Report Form 16 Appendix C - CONDOR Registration Request Form 18 1.0 - Acknowledgements PCBoard (C) 1985..1987 Clark Development Company, Inc. (Murray, UT) RBBS-PC (C) 1983..1987 D. Thomas Mack (Great Falls, VA) Microsoft, MS, and MS-DOS are registered trademarks of Microsoft Corporation. Within the context of this document, MS-DOS and PC-DOS are equivalent. Page 2 CONDOR.EXE - Installation and Use 1.1 - Limited License The CONDOR package, consisting of CONDOR.EXE and this document, CONDOR.DOC, is the exclusive property of Intermountain Softworks, P. O. Box 2043, Walla Walla, WA 99362. The package may also include certain non-copyrighted sample data and/or batch files. Users are granted a limited license to copy and freely distribute copies of the CONDOR package, so long as the distributed copies are unmodified, the copyright notice is neither changed, removed, or bypassed, and that an unmodified copy of this documentation accompany the package. The preferred method of distribution is via one's bulletin board system. Except for the actual cost of disk media, mailer, and postage, or the normal BBS subscription fee, if any, such distribution must be without charge. Although Intermountain Softworks is satisfied that this product will perform as represented, and that due care has been exercised in development, CONDOR is offered on an "as-is" basis, without warranty, either expressed or implied. By use of this product, the user assumes all risk, to include responsibility for installation consistant with examples included in this document, and as promulgated by the developers of PCBoard. The libraries we use under license are fully protected by federal law, as is CONDOR. 1.2 - Shareware Distribution It should be obvious that none of us is getting rich from BBS support applications and doors. CONDOR represents, by this time, far more hours of work than we imagined. The "work" is attempting to decipher what certain applications are doing, and what they expect, rather than writing brilliant code. If you wish to undertake this yourself (in lieu of our modest $10 fee), blessings and peace be upon you! Let us point out, however, that the present version is complex enough to preclude any justification in disassembly, or "reverse engineering," particularly when formats are subject to change within a matter of months. If you use CONDOR, you are EXPECTED to register your copy. Our thanks to the handful of SysOps who have done so. Whether we continue this project as shareware, or continue it at all, depends largely upon the monitary return on our investment in time. Profit, obviously, is hardly a motive at $10. The version-specific nature of CONDOR dictates a short shelf life. You also may need help, and we normally ignore operator pages from non-registered users. Page 3 CONDOR.EXE - Installation and Use Registered users will receive one year's complementary access to our PCBoard system for thirty-five minutes per day, and access to all operating "doors." Registration also entitles one to technical support within the scope of CONDOR, via our PCBoard system. A registration form is included for your convenience. 1.3 - What's New With Condor Two Automatic generation of support files. Other than RBBSxPC.DEF, which must be edited with CONFIG.EXE (ver 30.1 or later), all doorware support files are generated by CONDOR as necessary. Local mode doorware access from PCBoard. SysOps may now exit to any 15.1A doorware application from PCBoard, like any remote user. Even RBBS-PC SysOps can't do this with doorware! Trap errorlevel within calling batch file. If CONDOR aborts for any reason (abnormal termination), an errorlevel of 3 is passed to MS-DOS. This value may be trapped within the calling batch file, which then reinvokes BOARD.BAT for return to PCBoard. Network or DoubleDOS (tm) support under MS-DOS file sharing. Provided one's multi-node operation recognizes MS-DOS file sharing standards, CONDOR will now handle up to three nodes. Additional support is available, up to the present doorware limit of nine, on special order. 9600 bps now supported, removing previous limit of 2400. Diagnostic error messages. The increase in CONDOR's size is no cause for concern. Indeed, unless you have an accurate stopwatch, the difference in execution speed is negligible. Even with all of the diagnostic code in place, we noticed little difference between CONDOR 1.51 and Beta A of 2.00. The copy you have removes that, of course. Most of CONDOR's brief appearance is spent waiting on disk I/O, rather than massaging data. Data is transferred in "blocks," and further processed within memory, keeping disk access to a minimum. When you see the message, "Updating [drive/pathname] messages," CONDOR is finished. The subsequent lag is loading and initializing 230K of Tradewars or whatever. Page 4 CONDOR.EXE - Installation and Use 1.4 - Version-Specific Requirements CONDOR 2.0 is designed to operate with PCBoard 11.8D/E, and probably forthcoming version 11.9D/E. This compatibility is determined by the format of PCBOARD.SYS, and the method PCBoard presently uses to exit through doors. Doorware is an entirely different matter. Many of the routines within CONDOR are hard-coded to specific bytes within the RBBS-PC 15.1A definition file(s), the messages file, and the doorware applications, or more precisely, the manner in which 15.1A doorware interprets these files. If any of these character positions changes, even the number of commas within the .DEF files, you'll need another version of CONDOR. Unless, of course, doorware runs under PCBoard without any help from us. CONDOR 2.0, therefore, does not support versions of doorware prior to 15.1A. 1.5 - What's Needed In addition to the CONDOR package, now in your possession, you'll need the RBBS-PC 15.1A configuration utility, CONFIG.EXE. This utility is analogous to PCBSETUP.EXE. It also must be version 30.1 or later; earlier versions won't work. The file may be downloaded from us as CNFG301.ARC, without validation or other formality, or from any of the RBBS-PC systems cited in our resource list. Users should carefully review CDC's instructions for implementation of doors, contained within PCBOARD.DOC. The following sections build on that knowledge. Additionally, if you are operating a multi-node environment for PCBoard, and plan to make doors available to each node, you'll want to study CDC's discussion of network operation with their product. We have made no attempt to supplant this material, or your need to fully understand the requirements of network or multi-tasking software used. While not absolutely necessary, we suggest that you consider running doorware applications under MONITOR 15.1A, since this arrangement is clearly the intent of doorware's authors. MONITOR controls elapsed time (once invoked, without referencing time variables from the main program), and manages "door points" for the individual applications. MONI151A.ARC may be downloaded from us, from Bob Westcott's board, or from Loren Jones' board. The others may have it by this time. Our usual 24-hour validation applies for downloading. Page 5 CONDOR.EXE - Installation and Use Additional documentation. Other than briefly noting the essential options within CONFIG.EXE, we have not made any attempt to document its operation, nor have we treated RBBS-PC file formats or network matters. We invite your attention to Tom Mack's extensive and thorough documentation for RBBS-PC 15.1A, as well as the source code for it. MS-QuickBASIC programmers should have this as a standard reference. Tom will appreciate that we borrowed his file formats (impossible to avoid, because doorware uses them), but that the "language is different." 1.6 - Overview Our program "Condor" is not a trademark, and we hope that the only entity who has a vested interest in the name is a certain bird. Needless to say, we didn't ask the bird for permission to use his name. Condor is a convenient six-character filename (to allow space for the revision level). It is sort of an acronym for CONvert DoOR. It doesn't convert anything, but merely translates PCBoard's exit file PCBOARD.SYS into a format that version 15.1A doorware expects. Condor was originally written as a quick fix for our own problems in running "Tradewars" with PCBoard. At the time, we were not aware that doorware author Bob Westcott was making an attempt to support PCBoard SysOps with an MS-QuickBASIC effort called DOORCONV.EXE. We merely needed a small, fast utility that would do the necessary translation in a flash, and get out of the way. And, it needed enough flexibility to adapt to virtually any PCBoard subdirectory configuration. The concept of a "door to MS-DOS" within BBS software probably originated with Tom Mack and Jon Martin as part of their RBBS-PC development. Tom writes of "horizontal growth" and adds that the term "doors" was coined to eliminate any confusion with MS-Windows. Doors are not even remotely like "Windows"; indeed, a door is little more than an exit from the BBS to a separate application, on the tenuous thread of an MS-DOS batch file. We suspect that Microsoft never intended batch files to be invoked remotely by BBS patrons. The vehicle, however, is provided with MS-DOS, and with careful planning and judicious use of support utilities, batch files are secure enough. Page 6 CONDOR.EXE - Installation and Use A "conversion" utility like Condor shouldn't be necessary. Any programmer who spends all the time and trouble to write a door for either PCBoard or RBBS-PC may address both audiences with little additional effort. Ideally, a door configuration screen would ask under which system a user proposes to operate. Unless the door author has some political reason for limiting his product to one system or the other, the larger market potential in building flexible doors makes infinitely more sense. After all, shareware dollars are not that easy to find! 1.7 - Multi-Node Environment CONDOR 2.0 attempts to stay out of network or multi-tasking matters as much as possible. If you are successfully running PCBoard under a true network, or under DoubleDOS, CONDOR shouldn't give you any trouble. CONDOR's main functions are to ensure that files supporting doorware are where they're supposed to be, and to manage node record updates within the RBBS-PC messages file. CONDOR has control of this file only for an instant, and during that time, locks the entire file. After updating the appropriate node record with currently-logged user data, the lock is removed, and the file is closed. CONDOR places no other restrictions on the messages file. Since doorware only needs to read the appropriate node record once during initialization, we are confident that doorware follows a similar procedure, or at least relinquishes all further claim to the messages file once the data has been read. If this turns out to be a false assumption, CONDOR will complain with an error message, and abort after a default number of tries on the hijacked file. If your network or multi-tasking software requires unique filenames for all files, merely append the node number to CONDOR, and reference it that way within the invoking batch file. 2.0 - Getting Started The first step is to have CONFIG.EXE generate one or more RBBSxPC.DEF files. If you are running a single node, you should be able to use the .DEF file you already have, provided it was created with version 30.1 (or later) of the configuration utility. Page 7 CONDOR.EXE - Installation and Use If you are running a true network, or using DoubleDOS, you should start from scratch with the .DEF files. Upon initialization, CONFIG will ask, "Will you be running multiple copies of RBBS-PC (Yes or No)?" Obviously, if running a single node, answer "no." A "yes" answer will prompt "To which copy of RBBS-PC will these options apply (1 to 36)?" For a multi-node setup, you'll need to rerun config for EACH node, generating a separate and distinct RBBS1PC.DEF, RBBS2PC.DEF, etc., for EACH node. The .DEF file is unique to each node, and is NOT shared. Options which concern you are as follows: 1 - SysOps first name 2 - SysOps last name 10 - Are you using ANSI.SYS with a color monitor 16 - Name of RBBS-PC shown initially is (19 characters) 103- File RBBS builds dynamically to open a door 141- Maximum number of concurrent RBBS-PC's 201- Communications port to be used by RBBS-PC Option 10 is analogous to "seeing what the user sees" on PCBoard's local monitor. Since the ANSI driver is already loaded, this option merely enables graphics locally within doorware. Option 103 may be any legal filename, or may remain the default of RCTTY.BAT. CONDOR strips the drive specifier from this field, and substitutes the fully qualified pathname you've supplied as a target filespec (where the messages file is written). Option 141 is exceedingly important, since CONDOR uses this value to expand the messages file to the proper number of node records. It also references this value in writing currently-logged user data to the appropriate node record. If you are running two or three nodes, option 141 MUST reflect this. Option 201 tells doorware applications which COM port to use for the node in question. Messages files created by CONFIG.EXE may be deleted, since CONDOR creates its own, automatically. CONFIG's output will then be: Single node Multi node ----------- ---------- RBBS-PC.DEF RBBS1PC.DEF RBBS2PC.DEF etc. Page 8 CONDOR.EXE - Installation and Use 2.1 - Batch Files A typical batch file to invoke CONDOR and the individual doorware application should look like this: echo off cls c:\pcb\condor pcboard.sys c:\pcb\doors\messages /1 if errorlevel 3 goto exit cd\ cd\pcb\doors monitor 1 :exit cd\pcb c:\pcb\board.bat CONDOR's command line arguments are few and important; indeed, "condor" entered alone at the MS-DOS prompt will display the copyright box, advise that the argument count is invalid, and abort. In normal operation, of course, a calling batch file will supply the required arguments, as suggested above. When operating a single node, the trailing /1 is not necessary, since CONDOR defaults to one node, if no argument is provided. Multi-node operation REQUIRES the argument, and should reflect the node number this copy of CONDOR is serving - either 1, 2, or 3. Mundane details of where to write what are handled by the program, based entirely upon your command line arguments. Note also that the doorware application is called with a single argument. This is the node number, and MUST be supplied as a "1" if running a single node. With PCBoard, when running multiple nodes, it is necessary to provide a separate copy of the invoking batch file to each node. The following example would properly reside in node 2's default (or system) directory... Page 9 CONDOR.EXE - Installation and Use echo off cls c:\pcb\node2\condor pcboard.sys c:\pcb\doors\messages /2 if errorlevel 3 goto exit cd\ cd\pcb\doors monitor 2 :exit cd\pcb\node2 c:\pcb\board2.bat Observe our preferred use of fully-qualified pathnames. Some ill- behaved applications have been known to confuse MS-DOS, which normally remembers a batch file's subdirectory and last line executed. Calls to WATCHDOG may be safely removed, since no user intervention is allowed within the batch loop, and 15.1A doorware properly monitors the communications port for loss of carrier. WARNING: CDC's proprietary PCBTRAP.COM should be installed without fail for trapping attempted user breakouts, as well as fail-safe recovery from system errors that otherwise may abort to MS-DOS. Recall from CDC's discussion of C:\PCB\MAIN\DOORS.DAT, that this security file requires the ACTUAL filename of the door's primary batch file. If your door's controlling batch file were named BBSLIST.BAT, then that is the name that must appear within DOORS.DAT. Most of us prefer to shorten the name to a single word, like MONITOR. Page 10 CONDOR.EXE - Installation and Use 2.2 - Subdirectories Assuming CDC's standard model for running one or more main board doors (conference doors are also possible), where subdirectories are arranged as shown below, we'll walk you through installation of the doorware application, MONITOR. Drive C:\ (Root) | (Subdirectories) | +-----+------+------+---+--------------+ | | | | | Lotus WP dBase etc C:\PCB (Default) Sub Sub Sub | BOARD.BAT (or BOARDn.BAT) PCBOARD.EXE PCBOARD.DAT PCBOARD.SYS REMOTE.SYS Note: PCBTRAP.COM is normally EVENT.SYS installed via AUTOEXEC.BAT -> PCBTRAP.COM WATCHDG1.COM -> CONDOR.EXE -> MONITOR (.BAT file) | (All below would be C:\PCB\+name) | +-------+------------+--------+-----------+------------+-------+ | | | | | | | UP MAIN GEN HELP DOORS DL1 DL2 | | | | | | Files MSGS BLT HLPA MONITOR.EXE Files Uploaded FSEC BLTG thru MONITOR.* for to PWRD BLTxx HLPZ [*] MESSAGES Down Main TCAN etc... DIR etc... RBBS-PC.DEF Load Board DOORS.DAT DIRG etc... [*] RCTTY.BAT DOORS DOORSG [*] Automatic creation by CONDOR.EXE In particular, note that C:\PCB\DOORS is the default directory for all of the support files associated with doorware. The subdirectory name may be anything, of course, but less confusion may surface if you stick with our examples. CONDOR itself should reside in the same directory to which PCBoard writes PCBOARD.SYS (normally C:\PCB); again, to avoid confusion. We'll call C:\PCB the "system" directory. Multi-node operators will establish a separate system directory for EACH node, consistant with network or multi-tasking requirements of Page 11 CONDOR.EXE - Installation and Use PCBoard. Like PCBOARD.SYS, CONDOR.EXE is unique to EACH node, and a copy of CONDOR.EXE must reside in that node's system directory. 2.3 - Disk Buffers In the case of a CONFIG.SYS file which tells MS-DOS to trust one's judgment in a few matters, rather than reverting to defaults, most of us have safely specified FILES to equal some number, asked that MS-DOS install a RAMdisk, and have loaded the ANSI driver. Common sense may suggest that the operating system simply reads information from a disk and passes it directly to an application. This is not the case. An interim holding area, called a disk buffer, gets it first. A disk buffer is a 512-byte block of memory that MS- DOS uses to temporarily hold information it is reading from, or writing to, a disk. If the buffered data will be used repeatedly, access time will be improved significantly if MS-DOS does not have to reread the same data each time it is needed. Users are given the responsibility of telling MS-DOS how many 512-byte disk buffers to allocate. This is done within CONFIG.SYS, and uses the syntax... BUFFERS = nn where nn is an integer between 1 and 99. Each buffer requested will increase the resident size of MS-DOS by 528 bytes. Some simple algorithm could doubtless be written to suggest the optimum number of buffers for a particular configuration. For a 20- megabyte hard disk, with the number of subdirectories that PCBoard requires, the magic number, we believe, is between 15 and 25. The ultimate authority may be a stopwatch. 15 will astound you if you've accepted the MS-DOS default of 2; indeed, PCBoard subdirectory searches will appear almost instantaneous. Multi-node users should carefully examine network or multi-tasking documentation for restrictions on the use of buffers. 2.4 - Error Messages CONDOR 2.0 error messages are weighted toward the diagnostic, to include line numbers when appropriate. These will mean little to you, but will provide us with an "audit trail" of what may have happened, and where in the code it occurred. The error messages are more fully discussed in Appendix A, to include suggestions on what you might do to correct the error. If you can't resolve the problem yourself, fill out the software Page 12 CONDOR.EXE - Installation and Use problem report, and either mail it to us, or upload it as SOFTPROB.xxx, where "xxx" is the first three letters of your last name. Use a "/" as the first character when PCBoard prompts for a file description. Sorry for the formality, but the report form is designed to provide us with essential information about your particular configuration, and (we hope), provide a CLEAR explanation of what you observed. Please allow us the courtesy of 24 hours for a response via our PCBoard system. If we charged $50 or $60 for CONDOR on an advance basis, we'd install an 800 number for such things. Registered users get special treatment, of course. 3.0 - Resources The four major sources of RBBS-PC doorware are... 415-689-2090 CA Concord Jon Martin 4 Home of RBBS-PC West 701-293-5973 ND Fargo Loren Jones 4 Fargo PCUG,RBBS Beta 603-424-5497 NH Merrimack Bob Westcott 4 On-Line adventure,Ham 703-759-5049 VA Great Falls 703-759-9659 VA Great Falls Tom Mack 4 Home of RBBS-PC 3.1 - A Note for Door Developers The following PCBoard system maintains a private conference on the subject of doors. A restricted-distribution door kit is available to PCBoard licensees. 201-729-7410 NJ Lake Mohawk Paul Kopit B 4 Software Soc'ty,140M Also, we attempt to stay abreast of essential utilities and tools for door applications programmers. Feel free to call our system during the hours indicated. Page 13 CONDOR.EXE - Installation and Use Appendix A - Error Messages CONDOR 2.0 error messages have three general formats. The most common is a single static line, followed by the usual message for an abort: Invalid argument count Abnormal program termination In some cases, the error message will report where CONDOR expected to find a certain file, and didn't: Can't open file [drive/path] filename Abnormal program termination The rarest will include a line number: Line nnn: lseek to node record failed Abnormal program termination If any of the "Line nnn" messages involves "Permission denied" or "Resource deadlock would occur," there is little you can do except to try the procedure again, in local mode. Here are the error conditions that you CAN do something about: Can't open file CONDOR relies upon you to supply fully qualified pathnames through command line arguments within the invoking batch file. Your second argument (the target, or output, filespec) is the most critical. c:\pcb\doors\messages also tells CONDOR to look for RBBSxPC.DEF in the same location, and to write the config option 103 file in that location. "Can't open" most often means "can't find." DOS 3.00 or later version required Rare, because you wouldn't be running PCBoard with anything else. Invalid argument count Too many or too few command line arguments. See supplied batch file for an example of the proper format. Page 14 CONDOR.EXE - Installation and Use Invalid node number If the node number is supplied, it must be in the range of 1 to 3. Any other number generates this error. If no number is provided in the command line, 1 is assumed. Don't forget the forward slash as a delimiter. Line nnn: lseek to node record failed RBBS-PC messages file is corrupted. Delete this file and let CONDOR regenerate it from scratch - automatic if file missing. Line nnn: Permission denied Sharing violation. Usually indicates incompatibility or a hijacked file. Line nnn: Resource deadlock would occur Locking violation, after ten unsuccessful attempts. A sure sign of trouble. CONDOR doesn't trap for everything. For example, if you were to rename a bogus file to PCBOARD.SYS, CONDOR won't check the file for integrity, since under normal operation, the file would have been created only a moment before by the main program. We have yet to see this file corrupted. Another reason for using CONFIG to edit the RBBSxPC.DEF files, rather than a text editor! Page 15 CONDOR.EXE - Installation and Use Appendix B - CONDOR Problem Report Form Instructions: For fastest service, please complete this form with your favorite text editor, and upload to our PCBoard system as SOFTPROB.xxx, where "xxx" is the first three letters of your last name. Use a / as the first character when prompted for a description. Or, if you prefer, send hardcopy by mail. Attach additional sheets if necessary. Mailing address: PCBoard system: Intermountain Softworks 509/529-7229 P. O. Box 2043 Hours on title page Walla Walla, WA 99362 24-hour validation required for uploads Name:___________________________________ Registered user ($10 paid)? Company:________________________________ Yes [] No [] Address:________________________________ City,St,Zip:____________________________ [] Software problem Business or Data Phone:_________________ [] Documentation problem Home Phone:_____________________________ [] Other What is the three-digit VERSION number displayed in CONDOR's copyright box? ______ Computer make______________________model________cpu_________ Version of PCBoard in use:________ Doorware version_________ Are you running doorware under MONITOR 15.1A? [] Yes [] No Running PCBoard under a true network or DoubleDOS? [] Yes [] No If so, please detail your network or multi-tasking hardware: If so, please detail all software used for the network: What SPECIFIC error messages are you getting from CONDOR? Page 16 CONDOR.EXE - Installation and Use Appendix B - CONDOR Problem Report Form (continued) If a doorware application is resident, which one, and what error messages are you getting, if any? Please supply exact contents of batch file that invokes CONDOR: Please CLEARLY detail the problem (attach additional sheets if necessary): Please include suggestions for improvement, either in the program or the documentation. All suggestions become the property of Intermountain Softworks. Page 17 CONDOR.EXE - Installation and Use Appendix C - CONDOR Registration Request Form SEND TO: Intermountain Softworks P. O. Box 2043 Walla Walla, WA 99362 Quan Item Price Total [2.01] [ ] Diskettes $10:_____________________ [ ] Support $10:_____________________ Company P.O. +$ 5:_____________________ WA orders add 7.9%:_____________________ TOTAL (US dollars):_____________________ [] Check [] Money Order [] Company P.O. SHIP ORDER / USER MAIL / BBS VALIDATION Name:___________________________________ Company:________________________________ Address:________________________________ City,St,Zip:____________________________ Business or Data Phone:_________________ Home Phone:_____________________________ Choice of BBS password:_________________ (Limit of 12 characters, one word please!) Registered users automatically receive complementary validation on our PCBoard system, which operates 24 hours weekends, and between 1600h and 0600h Monday through Friday. On weekdays, the system is subject to availability after midnight (Pacific). 509/529-7229 No parity, 8 data bits, 1 stop bit Bit rates: 2400, 1200 Thank you! Page 18